# 6.2 Engine Configuration

# 1. Configuration Entry Point

The entry point for configuring the Enjoy engine is unified within the Engine class. The Engine class provides a series of setter methods to guide the configuration, reducing the cognitive load. For example:

// Enable hot reloading of templates, recommended to be set as true in most production environments, unless in extreme high-performance scenarios.
engine.setDevMode(true);

// Add shared template functions
engine.addSharedFunction("_layout.html");

// Enable fast mode, improves performance by 13%
Engine.setFastMode(true);

// New in jfinal 4.9.02: Support for Chinese expressions, variable names, method names, and template function names.
Engine.setChineseExpression(true);

1
2
3
4
5
6
7
8
9
10
11

Note: engine.setToClassPathSourceFactory(), engine.setBaseTemplatePath(...), and engine.setDevMode(...) should be placed at the beginning as subsequent configurations like engine.addSharedFunction(...) depend on these.

jfinal 4.9 introduced HTML compression, which can be configured as follows:

// Enable HTML compression, the separator character can be configured as '\n' or ' '
engine.setCompressorOn(' ');

1
2

This feature benefits high-concurrency web applications by saving bandwidth and improving efficiency. After configuration, the generated HTML content will look like the following:

Note: This feature only supports HTML compression. If HTML contains inline JavaScript, and the script includes single-line comments or missing semicolons, errors may occur. For example, the following JavaScript code:

// This is a JS comment
var s1 = "hello"
var s2 = "james"
s3 = s1 + s2

1
2
3
4

Here, the JS code contains single-line comments and missing semicolons at the end of some statements. For such HTML templates, use a newline character as the compression separator:

// Use newline character as separator
engine.setCompressorOn('\n');

1
2

This configuration yields the same compression rate as using a space character, but the compressed HTML is more readable. If your HTML contains JavaScript, it's strongly advised to use this setting.

jfinal 4.9 introduced addEnum(...) to support enum types:

// Assume the following enum definition
public enum UserType {
    ADMIN,
    USER;
    
    public String hello() {
        return "hello";
    }
}
        
// Add configuration for the enum
engine.addEnum(UserType.class);
 
// Usage in template
### The object 'u' is passed via Controller's setAttr("u", UserType.ADMIN)
#if(u == UserType.ADMIN)
    #(UserType.ADMIN)
 
    ### The following two lines demonstrate direct method calls
    #(UserType.ADMIN.hello())   
#end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

jfinal 4.9.02 introduced new configurations to support Chinese expressions, variable names, method names, and template function names:

Engine.setChineseExpression(true);

# 2. Configuring Multiple `Engine` Instances

The Enjoy engine is designed for multiple purposes; different modules within the same project can use different Engine instances for different purposes. Thus, they need to be configured separately, and their configurations are independent and do not interfere with each other.

For example, jfinal's Controller.render(String) and SQL management features like Model.template(...), Db.template(...), Db.getSqlPara(...) each use different Engine instances, so they need to be configured separately and at entirely different locations.

Configuration for the Engine instance used in Controller.render(String) is done in configEngine(Engine me):

public void configEngine(Engine me) {
  // Set devMode to true to enable template hot reloading
  me.setDevMode(true);
}

1
2
3
4

Configuration for the Engine instance used in SQL management is done in configPlugin(Plugins me):

public void configPlugin(Plugins me) {
  ActiveRecordPlugin arp = new ActiveRecordPlugin(...);
  Engine engine = arp.getEngine();
  
  // Code above gets the Engine instance used for SQL management; you can start configuring it now.
  engine.setToClassPathSourceFactory();
  engine.addSharedMethod(new StrKit());
  
  me.add(arp);
}

1
2
3
4
5
6
7
8
9
10

Common mistake: Some people configure the SQL management Engine instance within configEngine(Engine me), causing configuration mismatches.

Similarly, any Engine instances you create yourself also need separate configurations:

Engine engine = Engine.create("myEngine");
engine.setDevMode(true);

1
2

# 3. Managing Multiple `Engine` Instances

Engine instances created using Engine.create(engineName) can be conveniently retrieved at any location using Engine.use(engineName), making it very convenient to manage multiple Engine instances. For example:

// Create an Engine instance and configure it
Engine forEmail = Engine.create("forEmail");
forEmail.addSharedMethod(EmailKit.class);
forEmail.addSharedFunction("email-function.txt");
 
// Create another Engine instance and configure it
Engine forWeixin = Engine.create("forWeixin");
forWeixin.addSharedMethod(WeixinKit.class);
forWeixin.addSharedFunction("weixin-function.txt");

// Use the Engine instance named "forEmail"
String ret = Engine.use("forEmail").getTemplate("email-template.txt").renderToString(...);
System.out.print(ret);
 
// Use the Engine instance named "forWeixin"
String ret = Engine.use("forWeixin").getTemplate("weixin-template.txt").renderToString(...);
System.out.print(ret);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

As shown in the code above, Engine.use(...) allows you to retrieve Engine instances created by Engine.create(...). This feature not only facilitates independent configuration but also independent retrieval and usage.

# 4. Hot Reloading Configuration

To achieve maximum performance, the Enjoy engine caches template parsing results by default. Thus, changes to templates will not take effect after they've been loaded unless the following configuration is applied:

engine.setDevMode(true);

Setting it to devMode is essential for improving development efficiency in a development environment.

As the template parsing speed of Enjoy is about seven times faster than that of template engines like Freemarker and Velocity, and it also checks for template modifications, it's highly recommended to enable hot reloading by setting setDevMode(true) in most cases, unless your project is in an extremely high-performance scenario.

# 5. Shared Template Function Configuration

If you define template functions using the #define directive in a template and wish to use these template functions in other templates, you can configure as follows:

// Add shared functions, which can be used anywhere afterwards
me.addSharedFunction("/view/common/layout.html");

1
2

The code above adds a shared function template file layout.html, which uses the #define directive to define template functions. With this configuration, you can use the template functions defined in layout.html directly in any other place.

# 6. Loading Templates from Class Path and JARs

If your template files are located within the project's class path or inside a JAR file (Note: Maven project's src/main/resources is also part of the class path), you can configure using me.setToClassPathSourceFactory() and me.setBaseTemplatePath(null). Here's a code example:

public void configEngine(Engine me) {
   me.setDevMode(true);
 
   me.setBaseTemplatePath(null);
   me.setToClassPathSourceFactory();
 
   me.addSharedFunction("/view/common/layout.html");
}

1
2
3
4
5
6
7
8

Enjoy engine comes with FileSourceFactory and ClassPathSourceFactory to configure where templates are loaded from—either from the file system or from the class path and JAR files. The former is the default configuration, while the latter can be set using engine.setToClassPathSourceFactory().

You can also implement the ISourceFactory interface to extend your own strategy for loading templates from any source. Then switch to your extended strategy using engine.setSourceFactory(...).

Furthermore, you can implement the ISource interface and load template content through engine.get(new MySource(...)). Some users have already implemented DbSource to load templates from databases.

# 7. Development in Eclipse

When developing in Eclipse, you can disable automatic validation in the Validation settings by deselecting 'Html Syntax Validator'. This is because Eclipse cannot recognize the directives used by Enjoy, leading to yellow underlines beneath the directives, which is aesthetically unpleasing. For the specific configuration method, see the image below:

After completing the configuration, make sure to restart Eclipse for the changes to take effect. This operation does not affect functionality and is solely for improving code aesthetics, catering to perfectionists under the Virgo zodiac.

← 6.1 Overview 6.3 Expressions →